android-gradle-localization-plugin

Gradle plugin for generating localized string resources

Overview

This plugin generates Android string resource XML files from CSV file. Generation has to be invoked as additional gradle task.

Supported features

• non-translatable resources - translatable="false" XML attribute
• auto-escaping double quotes, apostrophes and newlines
• auto-quoting leading and trailing spaces
• syntax validation - duplicated, empty, invalid names detection
• comments

Usage

1. Add dependency to the top-level build.gradle file. Your file should look like this:

   
   buildscript {
      repositories {
          mavenLocal()
          mavenCentral()
      }
      dependencies {
          classpath 'com.android.tools.build:gradle:0.13.+'
          classpath 'pl.droidsonroids.gradle.localization:android-gradle-localization-plugin:1.0.+'
      }
   }
   

2. Apply plugin and add configuration to build.gradle of the application, eg:

   apply plugin: 'localization'
   localization
      {
          csvFile=file('translations.csv')
          OR
          csvFileURI='https://docs.google.com/spreadsheets/d/<key>/export?format=csv'
      }
   

   csvFileURI can be any valid URI, not necessarily Google Docs' one

3. Invoke localization gradle task. Task may be invoked from commandline or from Android Studio GUI.

   • from commandline: ./gradlew localization (or gradlew.bat localization on Windows)
   • from GUI: menu View->Tool Windows->Gradle and double click localization
     

   Non existent folders will be created. WARNING existing XML files will be overwritten.

Example

The following CSV file:

name,default    ,pl       ,comment   ,translatable
file,File       ,"Plik"   ,file label,
app ,Application,,,false

will produce 2 XML files:

• values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
  <string name="file">File</string><!-- file label -->
  <string name="app" translatable="false">Application</string>
</resources>

• values-pl/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
  <string name="file">Plik</string><!-- file label -->
</resources>

Configuration

localization extension in build.gradle can contain several configuration options. All of them except CSV file location are optional and has reasonable default values.
CSV file location. Exactly one of them must be specified:

• csvFile - CSV File, Gradle's file() can be used to retrieve files by path relative to module location or absolute
  
• csvFileURI - CSV file URI

CSV format:

• defaultColumnName - default='default', column name which corresponds to default localization (values folder)
• csvStrategy - default=null (library default strategy, equivalent of CSVStrategy.DEFAULT_STRATEGY)
  • see CSVStrategy javadoc, and sources since documentation is quite incomplete

The following options turn off some character escaping and substitutions, can be useful if you have something already escaped in CSV:

• escapeApostrophes - default=true, if set to false apostrophes (') won't be escaped
• escapeQuotes - default=true, if set to false double quotes (") won't be escaped
• escapeNewLines - default=true, if set to false newline characters won't be escaped
• escapeBoundarySpaces - default=true, if set to false leading and trailing spaces won't be escaped so they will be effectively removed at compile time
• convertTripleDotsToHorizontalEllipsis - default=true, if set to false triple dots (...) won't be converted to ellipsis entity &#8230
• escapeSlashes - default=true, if set to false slashes (\) won't be escaped
• normalizationForm - default=Normalizer.Form.NFC if set to null Unicode normalization won't be performed, see (javadoc of Normalizer)[http://docs.oracle.com/javase/8/docs/api/java/text/Normalizer.Form.html#NFC] for more details
• tagEscapingStrategy - default=IF_TAGS_ABSENT, defines X(H)TML tag brackets (< and >) escaping strategy possible values:
  • ALWAYS - brackets are always escaped. Eg. "<" in source becomes "&lt;" in output XML
  • NEVER - brackets are never escaped. Eg. "<" in source is passed without change to output XML
  • IF_TAGS_ABSENT - Brackets aren't escaped if text contains tags. Eg. <b>bold</b>} will be passed without change, but "if x<4 then…" becomes "if x&lt;4 then…". See JSoup - library used to detect tags

Advanced options:

• ignorableColumns - default=[], columns from that list will be ignored during parsing
• allowNonTranslatableTranslation - default=false, if set to true resources marked non-translatable but translated are permitted
• allowEmptyTranslations - default=false, if set to true then empty values are permitted

License

MIT License
See LICENSE file.